---
description: >
  Simple markup language documenting Ruby code.
title: "Rdoc"
---

Document Ruby code using simple comments.

<details markdown="1" id="table-of-contents">
<summary>
Table of Contents
</summary>

* TOC
{:toc}
</details>

## Markup

### Headings

```ruby
# = H1
# == H2
```

And so forth.

### Paragraphs

```ruby
# Paragraph
# Still Paragraph
#
# New Paragraph
#
#   this.will.be(verbatim)
```

#### Inline modifiers

Inline text modifiers.

<div markdown="1" class="table">

| HTML            | RDoc     |
|-----------------|----------|
| `<em>text</em>` | `_text_` |
| `<b>text</b>`   | `*text*` |
| `<tt>text</tt>` | `+word+` |

</div>

Precede first control-char with `\` to escape it.

#### Links

Classes, source files, and method names are linked automatically using plain text
Eg. `http:`, `mailto:`, `ftp:`, and `www.` prefixes.

Images are turned into `<img>`s automatically.

Use `link:asd/asd.html` for links relative to `-op` dir.

Labeled links with either one of:

```ruby
label[url]
{multi word label}[url]
```

#### Lists

Lists are typed as indented paragraphs with:

```ruby
# Regular paragraph
#   * bullet list
#   - bullet list
#   1. numbered list a. alpha list
#   A. alpha list
```

##### Labeled Lists

```ruby
# [cat] small domestic animal
# [+cat+] command to copy standard input
```

For tabular format:

```ruby
# cat::   small domestic animal
#         indent the second line
# +cat+:: command to copy standard input
#   you don't have to indent all the
#   way though
```

#### Horizontal Rules

```ruby
# --- or more hyphens
```

## Doc Modifiers

### Method calls

Beginning of method comment `call-seq:`.

```ruby
# call-seq:
#   function(arg1,arg2) => result
#   function(arg1, arg2, arg3) => res
#
# Begin description
```

### Stop Comments

<div markdown="1" class="table">

| Description                                   | Modifier                   |
|-----------------------------------------------|----------------------------|
| omit documentation                            | `:nodoc:` / `:nodoc: all`  |
| Document nothing further at the current level | `:enddoc:`                 |
| Toggle current scope documentation            | `:stopdoc:` / `:startdoc:` |
| alias toggle current scope documentation      | `--` / `++`                |

</div>

For example,

```ruby
# rdoc Comment line
#--
# Not a rdoc comment
#++
# rdoc again
```

### Yield arguments

Relabel yield arguments.

```ruby
def fred # :yields: index, position
  yield line, address
end
```

### Titles

```ruby
# --------------------------------------
# :section: My Section
# This is the section that I wrote.
# --------------------------------------
```

### Other modifiers

<div markdown="1" class="table">

| Description                                   | Modifier                   |
|-----------------------------------------------|----------------------------|
| Don't use initialize signature                | `:notnew:`                 |
| Insert file `filename`                        | `:include:filename`        |
| Set document title to `text`                  | `:title:text`              |
| Class `name` will appear on the index page    | `:main:name`               |

</div>

For more details read the
[official documentation](https://ruby-doc.org/stdlib-2.6/libdoc/rdoc/rdoc/RDoc/Markup.htmlhttps://ruby-doc.org/stdlib-2.6/libdoc/rdoc/rdoc/RDoc/Markup.html){:rel="nofollow noreferrer noopener"}

_Original by jan.varwig.org. Licensed under Creative Commons BY-SA._
